Just Call Me Internet

home *** CD-ROM | disk | FTP | other *** search

/ Just Call Me Internet / Just Call Me Internet.iso / others / crypt / ezpgp092 / tos2gem / tos2gem.txt < prev

Wrap

Text File | 1995-09-10 | 19.5 KB | 428 lines

Brief documentation for TOS2GEM dated 26.07.1995, position at 03.08.1995 ======================================================================== 1. What is TOS2GEM? ------------------- TOS2GEM is an Auto folder program which GEM applications can access in a flexible way to display the output from TOS and TTP programs as VDI text in a Console window. TOS2GEM makes the ideal Console window for use with shells or alternative desktops and saves the programmer some effort! TOS2GEM was principally designed for use under Single TOS and although it runs fine under Geneva, MagiC and MultiTOS its use there is limited as under these systems TOS programs run in windows anyway (if they have been started correctly). The most important TOS2GEM features at a glance: - Gives prorammers a clean way of redirecting the output of TOS/TTP type programs into a GEM window. - Simulates TOS screens of various sizes (not just boring 80x25) that may optionally be only partly visible. - Works with all monospaced fonts irrespective of size. - Optional output buffer allows faster output than with GEMDOS/BIOS (only for SingleTOS/MagiC). - Optional scroll-back buffer allows output to be reviewed. - Offers almost complete VT52 emulation (colour sequences optional only) 2. Installation --------------- Copy TOS2GEM.PRG to the Auto folder of your boot partition. TOS2GEM installs a Cookie during booting which programmers can use to control some of TOS2GEM's functions. TOS2GEM.PRG can also be run from the desktop. 3. What is T2GRESET.PRG? ------------------------ Programs must reserve TOS2GEM for themselves; until released other programs cannot make use of TOS2GEM. If a program which had reserved TOS2GEM crashes or is exited without releasing TOS2GEM, you can use T2GRESET.PRG from the desktop to release TOS2GEM. It's not a good idea to run T2GRESET.PRG if an application which has reserved TOS2GEM is still running, as this inevitably causes serious complications. Signs that a lock-up has taken place are if no program using TOS2GEM will run, and a newly-started one reports that it cannot make a reservation. 4. What is T2G_INTR.PRG? ------------------------ Since the beta-version dated 09.07.1995, TOS2GEM uses the vertical-blank interrupt during time-controlled buffering to trigger screen refreshes even when there has been no TOS-output for some time (previously checks for exceeding the given period were only made during output). If this should unexpectedly lead to problems (e.g. unexplained crashes while output redirection is active), one can use T2G_INTR.PRG to switch off the use of this interrupt (and to switch it on again, if desired, by running the program a second time). If one wishes or needs to disable the use of the VBL interrupt permanently, then T2G_INTR.PRG should be placed physically after TOS2GEM.PRG in the AUTO folder. Important: Those who have previously included the mini-package of TOS2GEM (see Section 9) with their programs mustn't overlook the fact that T2G_INTR.PRG has now been included in this package! 5. What are T2G_TEST.PRG and PRIME_NO.TOS? ------------------------------------------ (These have been renamed from the German T2G_BSP.PRG and PRIMZAHL.TOS so that the titles indicate their purpose better to English-speaking users). Since it is difficult to visualise from the theoretical description of TOS2GEM operation what the program actually does, I wrote a small test program (namely T2G_TEST.PRG, meaning TOS2GEM-test). These two programs are incidentally not contained in the mini-package (see Section 9). After starting the test program (TOS2GEM must of course have been started first) a dialog box appears in which one can input the dimensions of the TOS screen that TOS2GEM is to simulate, and the maximum area that is to be visible. One can also choose here whether and how output buffering and colour support of TOS2GEM is to be used. Following this a corresponding window will be opened (already using the TOS2GEM redirection) into which the realised dimensions will be written. Immediately after this the PRIME_NO.TOS program (that has to be in the same directory) will be started; it can execute simple prime number calculations using the 'Sieve of Eratosthenes' method (one can also use any other TOS program, it just has to be re-named to PRIME_NO.TOS and placed in the correct directory). To use it, just follow the prompts; note that you have to type 'j' for 'Yes' (which in German is 'ja'). After ending the prime number program one can move the window, into which the output was redirected cleanly, around the screen. Clicking on the Closer symbol at top left quits the program. A click inside the window area brings up an alert box offering three options: 'Resize' permits altering the TOS2GEM window area (with the same dialog that appeared at the start; during this the whole screen will be cleared if its total size is changed). With 'Rerun' one can start PRIME_NO.TOS again, while 'Nothing' does just that... The test program has been kept simple deliberately, partly so one can see that TOS2GEM support is quite easy to realise. Not all the options of TOS2GEM are demonstrated (in particular, neither multiple fonts in various sizes are used nor is a scroll-back buffer implemented), but there should still be enough to illustrate the opportunities that TOS2GEM offers. Those who would like to have the source code in order to get a concrete picture of what TOS2GEM support involves should apply to me (see below). Since the source has now been extensively commented (in German!) and a number of library functions have been included directly so that it can be compiled on its own, it has grown to a stately 46 kB in the meantime. However the portion needed only for TOS2GEM support is relatively small (not including the comments), so don't be frightened... 6. Where is the programmers documentation? ------------------------------------------ It's still not quite complete at the moment. I have decided to release the hypertext with information (not only) for programmers in its still incomplete form, since it has now become at least half-way usable. To view it you need ST-Guide by Holger Weets, who I wish to thank once more here for this wonderful tool. In addition, those who understand German will find articles in ST-Computer magazine for 04/95 and 05/95 very helpful. Furthermore it is suggested that all programmers should take a look at the TOS2GEM library from Dirk Klemmt (klemmt@stud.uni-frankfurt.de) for Pure and Gnu C, since this makes the use of TOS2GEM childishly easy. A short overview of its capabilities can be obtained from ST-Computer 05/95. Those wanting to know more should approach Dirk, since I have had little or nothing to do with the library itself. 7. INSPECT.TTP -------------- This tiny program serves as an aid for programmers who want to write applications with TOS2GEM support. You will find more about this in the text and hypertext files. 8. Disclaimer ------------- Although TOS2GEM and the associated utilities have been carefully programmed and thoroughly tested I cannot guarantee that no bugs remain. Therefore I cannot guarantee either the fault-free operation of TOS2GEM, nor its fitness for any particular purpose. You use TOS2GEM at your own risk! I, Thomas Binder, do not accept any liability or responsibility for any direct or indirect damage that may arise, either financial, material or any other kind, from either the use or misuse of TOS2GEM and its associated applications, utilities and documentation. All trademarks mentioned in the TOS2GEM documentation are acknowledged and recognised. 9. Distribution of TOS2GEM -------------------------- TOS2GEM is freeware and may be copied and used freely. However distribution may take place only in one of two variants, where all the named files have to be copied unchanged in each case (archiving is permitted): a) Complete package Contains TOS2GEM.PRG, T2GRESET.PRG, T2G_INTR.PRG, TOS2GEM.H, TOS2GEM.TXT, T2G_TEST.PRG, PRIME_NO.TOS, INSPECT.TTP, TOS2GEM.HYP and TOS2GEM.REF. This package is mainly intended for distributing TOS2GEM on its own (when it is not included with another program). b) Mini-package Contains only TOS2GEM.PRG, T2GRESET.PRG, T2G_INTR.PRG and TOS2GEM.TXT. This variant should only be used when one wants TOS2GEM to accompany a program that requires it. Those who have developed their own programs that need or support TOS2GEM may include TOS2GEM in their program package (in one of the above- mentioned forms) under the following conditions: - TOS2GEM must be copied to its own folder - The documentation or the program must contain instructions for using TOS2GEM - It must be clear from the documentation that TOS2GEM is a separate, free-standing utility developed by me, and that it does not belong to the actual program. Furthermore I would be most grateful if you would send me a sample of the program. 10. Contact with the author --------------------------- For those who have found errors, would like the test program source code, need help with programming TOS2GEM applications, want to express praise, criticism or simply to chat, here are my details: Thomas Binder Johann-Valentin-May-Strasse 7 64665 Alsbach-Haehnlein Germany InterNet: binder@rbg.informatik.th-darmstadt.de IRC: Gryf Please include a disk and SAE (Self Addressed Envelope) along with either an International Reply Coupon or a second disk, or be in a position to receive binaries via E-mail. You should also state whether you want the old or new source for T2G_BSP.TOS (renamed T2G_TEST.TOS in English). In the new version a somewhat more complicated, but multi-tasking friendly method is used for control, whereas the older version proceeds 'conventionally'. The new version is recommended only for those that already have some experience with TOS2GEM! For beginners I recommend the older source code. TOS2GEM has taken a considerable amount of my free time to develop and if you'd like to contribute to ensure I continue to support the Atari platform please don't hesitate to do so! This is aimed particularly, but not exclusively, at those that want to support TOS2GEM in their own programs. My banking arrangements are: Dresdner Bank AG Frankfurt am Main Account No: 9 024 050 00 Sort code: 500 800 00 Thanks a lot! 11.British support ------------------- British support for the English-language version of TOS2GEM is provided by Denesh Bhabuta at: CyberSTrider 203 Parr Lane Unsworth Bury Lancashire BL9 8JW He will be pleased to accept any contributions on behalf of the TOS2GEM author gratefully, sent by Sterling or Euro-cheque, International Money Order or Postal Order; a minimum of 6 is recommended. Denesh also supports other Freeware and Shareware, much of it of recent German origin. He may be contacted by E-mail at: dbhabuta@cix.compulink.co.uk or danny@micros.hensa.ac.uk 12. What programs support TOS2GEM? --------------------------------- Currently three main programs use TOS2GEM as Console windows: - POVSHELL v1.3 onwards, programmed by Dirk Klemmt: Email: klemmt@stud.uni-frankfurt.de - Thing alternative desktop, programmed by Arno Welzel: Email: aw@zaphot.augusta.de - The shell Easy-PGP by Manfred Ssykor: Email: msy@lafp.tng.oche.de Other programmers are interested but until I'm 100% certain we'll leave it at that. At this time I would like to repeat an open call to all who have previously shown an interest: Let's hear from you! I would be glad of some more feedback so that I know whether and what things you are programming with TOS2GEM. 13. Credits and thanks ---------------------- The following people either directly or indirectly took part in the development of TOS2GEM (in alphabetical order): - Alexander Clauss - Joe Connor - Frank Danapfel - Dirk Klemmt - Harald Schnfeld - Thomas Schulze - Manfrd Ssykor - Arno Welzel In addition I would like to thank all those who have been willing to send me a contribution for TOS2GEM. 14. Outloook for further development of TOS2GEM ----------------------------------------------- Up to now there have been problems when one uses TOS2GEM and Gemini together (not fundamentally, but in certain situations - see hypertext). To overcome this will be the next step. Oh yes, sometime I should also finish writing the docs.... 15. History ----------- This history only contains the changes since the last pre-release beta-version of TOS2GEM, since otherwise it would be a bit long... TOS2GEM dated 26.07.1995: - Stupidly the MiNT cookie was only interrogated when starting TOS2GEM, therefore TOS2GEM also used buffering under MiNT if it was started first (the recognition of input calls doesn't work with MiNT, therefore one must not buffer). - The TOS2GEM test program now uses the option to reserve TOS2GEM really only when required. One can therefore start it repeatedly (with multi-tasking), as TOS2GEM is not permanently engaged. TOS2GEM-beta dated 09.07.1995: - A number of errors and inadequacies with the 'stats' evaluation removed. - With time-controlled buffering TOS2GEM now uses the VBL-interrupt, to trigger a screen refresh even when there has been no TOS-output for some time (previously checks for exceeding the set period were only made during output). - New file 'T2G_INTR.PRG' that switches on and off the use of the interrupt in cases when problems arise. - With buffering active TOS2GEM now also empties the buffer when the visible area is moved. TOS2GEM dated 21.06.1995: - New 'stats' Cookie-element, in which the contents of several internal variables are stored when output redirection is not activated so that they can be read out later (more about this in the docs). TOS2GEM-beta dated 01.06.1995: - During initialisation of the text buffer, setting of null-bytes for line-ends was left out (the source line seems to have got lost when colour support was added...) TOS2GEM-beta dated 11.05.1995 - Serious error under MiNT removed: Due to carelessness in the source, buffering also took place under MiNT, though input recognition does not work in that case. - TOS2GEM can now also use time-controlled output buffering; with this, screen refreshes take place at pre-set time intervals. This is achieved by negative values in the 'buffer_output' Cookie-element. - Line redraw in colour mode has been converted to a 'flicker-free' method, which, though a little slower, is kinder on the eyes. TOS2GEM-beta dated 07.04.1995 - TOS2GEM can now also handle colour sequences (in which I also include those for inverted video)! The new 'color' Cookie-element determines the type of colour support (compatible or VDI- conforming). More about this in the HYP doc, which has now been released. - Under SingleTOS, TOS2GEM output buffering now also uses a timer triggering a refresh after 500 ms for Bconstat calls. Thanks to this, TOS programs that interrogate the keyboard via Bconstat/Bconin will work correctly (e.g. SYSOK). Under MagiC this is unnecessary, as there the buffer will be cleared at each Bconstat call anyway. TOS2GEM dated 24.03.1995 - Since I was informed in a bug report that the TOS2GEM Cookie was still present after a reset, TOS2GEM now also hooks into the reset vector to clear the Cookie pointer even when it only has to extend the Cookie-jar. I hope that this has removed the problem (I couldn't reproduce it). - With output buffering active, a refresh is now also performed when the screen contents have (internally) moved by the window height. Thanks to this, no output will get lost completely. TOS2GEM-beta dated 02.02.1995 - Keyboard input is recognised now also under MagiC, so that buffering is also possible with this operating system. Unfortunately it doesn't work with MiNT/MultiTOS (though here one is likely to forego TOS2GEM in favour of TOSWIN/MINIWIN, which natutally also applies to VT52 under MagiC). - Buffering could be improved once more, so that output is more than twice as fast as without buffering (this is in part faster than the standard GEMDOS/BIOS output). TOS2GEM-beta dated 31.01.1995(?) - With the new 'buffer_output' Cookie element one can achieve buffering of the output, which results in a marked increase in speed. Unfortunately this only works under SingleTOS, as only there can TOS2GEM recognise keyboard output correctly (it is necessary to clear the buffer in this case, so one can recogise what should be input). TOS2GEM dated 19.01.1995 - If TOS2GEM had to create or extend the Cookie-jar, this was lost when output redirection was first activated as it lay in the same memory region as the VDI array. TOS2GEM dated 03.01.1995 - In re-activating output redirection via 'switch_output', the Y-offset was not adapted correctly. Since this was not an insignificant error, it is advisable to use at least this version (note the 'date' Cookie-element!) in programs in which the size of the TOS2GEM window can be altered. - TOS2GEM.PRG now has the memory protection flag 'global' once again (I forgot it the last time, because the Pure C linker unfortunately can't do this (at least that of PC 1.0)). - The header file has been improved: The constant RESERVED_SIZE now exists for the reserved field of the Cookie, specifying the size of this field. TOS2GEM dated 12.12.1994: - A small error occurred during calculation of two internal variables that resulted in faulty scrolling in some circumstances (if only the first pixel row of a line was visible). - TOS2GEM test example included in the 'large' archive, so that one can see what the purpose of TOS2GEM is and how it works. I hadn't thought of this at first (thanks to Dirk Klemmt, who brought this omission to my attention). TOS2GEM dated 22.11.1994: - First official version, unfortunately without ST-Guide documentation (I wanted to release TOS2GEM at the proTOS...) - A problem under MagiC that switches on the 'real' cursor for an 'Fread' call for the console and completely misplaces the one for TOS2GEM has now been circumvented. Though the solution was not a 'clean' one (write access to the negative LineA variables), I could not find any other reliable method. - TOS2GEM now has a 'Global' memory protection flag, so that no problems arise in this respect with Mint/MultiTOS. 15. English translation ----------------------- English version of this document by Joe Connor, with additions and corrections in various files by Peter West (who is also responsible for the hypertext translation).